.\" 
.\" mdoc-update manual page.
.\" (C) 2008 Jonathan Pryor
.\" Author:
.\"   Jonathan Pryor (jpryor@novell.com)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "mdoc-update" 1
.SH NAME
mdoc update \- \fBmdoc\fR(5) documentation format support
.SH SYNOPSIS
\fBmdoc update\fR [OPTIONS]* ASSEMBLIES
.SH DESCRIPTION
\fBmdoc update\fR is responsible for the following:
.TP
.B *
Creating documentation stubs based on \fIASSEMBLIES\fR.  The stub-creation
process will create new \fBmdoc\fR(5) XML files for each type within
\fIASSEMBLIES\fR, and provide documentation stubs for each member of those
types.
.TP
.B *
Update documentation stubs based on \fIASSEMBLIES\fR.  Existing \fBmdoc\fR(5)
documentation can be updated to reflect changes within \fIASSEMBLIES\fR, such
as added types and members, while preserving existing documentation.
.Sp
In some limited circumstances, renames will be tracked, minimizing the
documentation burden when e.g. a parameter is renamed.
.PP
\fBmdoc update\fR does not rely on documentation found within source code,
though it can import XML Documentation Comments via the \fB\-i\fR option.
.PP
See \fBmdoc\fR(1) and \fBmdoc\fR(5) for more information.
.SH OPTIONS
.TP
.B \-\-delete
Allow \fBmdoc update\fR to delete members from documentation files.  
The only members deleted are members which are no longer present within
\fIASSEMBLIES\fR and are not present in any other assembly versions.
.Sp
If a type is no longer present, the documentation file is \fInot\fR
deleted, but is instead \fIrenamed\fR to have a \fB.remove \fR extension.
.Sp
Version detection is done with the \fI//AssemblyVersion\fR elements; if there
are no \fI//AssemblyVersion\fR elements for a given \fI<Type>\fR or 
\fI<Member/>\fR, then the \fI<Type>\fR will be renamed and/or the 
\fI<Member/>\fR will be removed.
.TP
\fB\-\-exceptions\fR[=\fISOURCES\fR]
EXPERIMENTAL.  This is not 100% reliable, but is intended to serve as an aid
for documentation writers.
.Sp
Inspect member bodies to determine what exceptions can be generated from the
member.
.Sp
\fISOURCES\fR is an optional comma-separated list of the following sources
that should be searched for exceptions:
.Sp
.nf
        added   Only generate <exception/> elements for members 
                  added during the current program execution.
                  This keeps mdoc-update from re-generating
                  <exception/> elements for all members (and thus
                  prevents re-insertion for members that had the
                  <exception/> elements removed).
        all     Find exceptions created in the member itself, 
                  references to members in the same assembly, 
                  and references to members in dependent 
                  assemblies.
        asm     Find exceptions created in the member itself and
                  references to members within the same assembly
                  as the member.
        depasm  Find exceptions created in the member itself and
                  references to members within dependent 
                  assemblies.
.fi
.Sp
If \fISOURCES\fR isn't provided (the default), then only exceptions created 
within the member itself will be documented.
.Sp
LIMITATIONS: Exception searching is currently implemented by looking for the
exception types that are explicitly created based on the known compile-time
types.  This has the following limitations:
.RS
.ne 8
.TP
.B *
This will not find exceptions which are implicit to the IL, such as
NullReferenceException and IndexOutOfRangeException.
.TP
.B *
This will find exceptions which are \fInot\fR thrown, e.g.
.nf

    public void CreateAnException ()
    {
        Exception e = new Exception ();
    }

.fi
.TP
.B *
This will not "follow" delegate and interface calls:
.nf

    public void UsesDelegates ()
    {
        Func<int, int> a = x => {throw new Exception ();};
        a (4);
    }

.fi
The function \fIUsesDelegates()\fR won't have any exceptions documented.
.TP
.B *
This will find exceptions which "cannot happen", such as
ArgumentNullExceptions for arguments which are "known" to be non-null:
.nf

    public void A ()
    {
        B ("this parameter isn't null");
    }

    public void B (string s)
    {
        if (s == null)
            throw new ArgumentNullException ("s");
    }

.fi
For the above, if \fB--exceptions=asm\fR is provided then \fIA()\fR will be
documented as throwing an ArgumentNullException, which cannot happen.
.ne
.RE
.TP
\fB\-f\fR=\fIFLAG\fR
Specify a flag to alter behavior.  Valid flags include:
.RS
.ne 8
.TP
.B no-assembly-versions
See the \fB-fno-assembly-versions\fR documentation, below.
.ne
.RE
.TP
\fB\-fno-assembly-versions\fR
Do not generate \fI/Type/AssemblyInfo/AssemblyVersion\fR and
\fI/Type/Members/Member/AssemblyInfo\fR elements.
.Sp
This is useful to prevent "churn" during updates.  Normally, if a type or
member hasn't changed but the assembly version has changed, then all types and
members will be updated to include a new \fI//AssemblyVersion\fR element, thus
increasing the amount of changes that need review before committing (assuming
all changes are actually reviewed before commit).
.Sp
WARNING: This \fIwill\fR interact badly with the \fB--delete\fR option, as
\fB--delete\fR uses the \fI//AssemblyVersion\fR elements to track version
changes.  Thus, if you have a member which is present in an early assembly
version and is removed in a subsequent assembly version, such as
\fISystem.Text.UTF8Encoding.GetBytes(string)\fR (which is present in .NET 1.0
but not in .NET 2.0), then the member will be removed when the
\fB--delete -fno-assembly-versions\fR options are specified, the member was
present in an earlier version of the assembly, and the current version of the
assembly does not contain the member.
.Sp
Consequently, this option should \fIonly\fR be specified if types and members
will \fInever\fR be removed from an assembly.
.TP
\fB\-i\fR, \fB\-\-import\fR=\fIFILE\fR
Import documentation found within \fIFILE\fR.
.Sp
\fIFILE\fR may contain either \fIcsc /doc\fR XML or \fIECMA-335\fR XML.
.TP
\fB\-L\fR, \fB\-\-lib\fR=\fIDIRECTORY\fR
Add \fIDIRECTORY\fR to the assembly search path, so that dependencies of
\fIASSEMBLIES\fR can be found without documenting those assemblies.
.TP
\fB\-o\fR, \fB\-\-out\fR=\fIDIRECTORY\fR
Place the generated stubs into \fIDIRECTORY\fR.
.Sp
When updating documentation, \fIDIRECTORY\fR is also the source directory.
.TP
\fB\-r\fR=\fIASSEMBLY\fR
\fIASSEMBLY\fR is a dependency for one of \fIASSEMBLIES\fR which should
\fInot\fR be documented but is required to process one of \fIASSEMBLIES\fR.
Add the directory containing \fIASSEMBLY\fR to the assembly search path.
.Sp
This option is equivalent to specifying \fB\-L\fR `\fIdirname\fR ASSEMBLY`.
.TP
\fB\-\-since\fR=\fIVERSION\fR
When \fIupdating\fR documentation for an assembly, if a type or member is
encountered which didn't exist in the previous version of the assembly a
\fB<since version="\fR\fIVERSION\fR\fB"/>\fR element will be inserted.
.TP
\fB\-\-type\fR=\fITYPE\fR
Only update documentation for the type \fITYPE\fR.
.TP
.B \-h, \-?, \-\-help
Display a help message and exit.
.SH SEE ALSO
mdoc(1), 
mdoc(5), 
mdoc-assemble(1),
mdoc-export-html(1),
mdoc-validate(1),
.SH MAILING LISTS
.TP
Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
.SH WEB SITE
Visit http://www.mono-project.com for details
